docs: add migration guide for Indy to did:webvh AnonCreds issuance#4059
docs: add migration guide for Indy to did:webvh AnonCreds issuance#4059PatStLouis wants to merge 5 commits intoopenwallet-foundation:mainfrom
Conversation
Adds a strategic guide for issuers transitioning from Indy-based AnonCreds credentials to did:webvh-rooted ones. Covers prerequisites, dual-issuance transition strategy, step-by-step setup, and impact on controllers and verifiers. Closes openwallet-foundation#3885 Signed-off-by: Patrick St-Louis <patrick.st-louis@opsecid.ca> Co-authored-by: Cursor <cursoragent@cursor.com>
esune
left a comment
esune
left a comment
There was a problem hiding this comment.
Looks good to me, it should be enough for issuers and verifier to at least get started and work towards migrating.
|
|
||
| ## Migration Strategy: Dual-Issuance Transition | ||
|
|
||
| The recommended approach is a phased transition where Indy and did:webvh |
There was a problem hiding this comment.
I disagree with this. I think the recommended approach is an abrupt issuance transition from Indy to did:webvh, and a transitioned holding period where some holders have Indy-rooted credentials from before the transition, and some have did:webvh-rooted from after. I can't see a case where you would want to issue the same credentials at the same time.
There was a problem hiding this comment.
this makes the assumption that all wallets already support webvh. If we are ok with this assumption, then we can change it. If holders don't support webvh and you abruptly stop issuing indy, this can have adverse effects.
There was a problem hiding this comment.
I evidently didn't pay enough attention on the first pass, I agree with @swcurran on the fact that while Indy and WebVH credentials can coexist, the recommended approach should be to start issuing on WebVH and only support revocation of Indy credentials while phasing out, at least when considering a creddef that is migrated from one technology to the other.
| 1. Set up the did:webvh infrastructure (server, witness, plugin) alongside | ||
| your existing Indy configuration. | ||
| 2. Create a did:webvh DID for your issuer. | ||
| 3. Re-register your schemas and credential definitions under the new DID. |
There was a problem hiding this comment.
I don't think the "Re-" is needed -- these are new objects. Picky, picky...
| your existing Indy configuration. | ||
| 2. Create a did:webvh DID for your issuer. | ||
| 3. Re-register your schemas and credential definitions under the new DID. | ||
| 4. Start issuing new credentials using the did:webvh credential definitions |
There was a problem hiding this comment.
I think we need to call out here that the new identifiers be shared with verifiers as much as possible for a period before issuance of did:webvh-rooted credentials begins. This allows verifiers to update their presentation requests to accept credentials rooted in either VDR. During this period -- the did:webvh objects exist, but are not being used for issuance. We might leave an AB testing exception to verify being able to issue a credential or two for testing, but not general use.
| 6. Communicate the transition to your verifier ecosystem so they can prepare | ||
| to resolve did:webvh identifiers. | ||
|
|
||
| ### Phase 3 -- did:webvh Only |
There was a problem hiding this comment.
"Phase 3 - Switch to did:webvh Issuing"
swcurran
left a comment
swcurran
left a comment
There was a problem hiding this comment.
Overall a really good document. Let's debate my points. As well, consider framing this as a generalized way to transition issuing from one credential format/type to another. I'd like the document title to change, but the general transition model can be repeated in other scenarios.
|
@swcurran I think a lot of this comes down to, how much should the issuer be limited by it's ecosystem? If an issuer needs to wait for all holders and verifiers to support their updated components, this creates a limitation on the least up to date entity. Its hard to describe this in an upgrade guide with a decentralized ecosystem in mind. An issuer might not have a way to contact all verifiers. I think a lot of this wording can be massaged in the "transition" phase. Issuers might not know which wallet software stores their credentials, same for verifiers. Issuers can publish a notice of their upcoming changes, but may not have direct line of communication with wallet / service providers. |
|
They might have "critical" lines of business where they just must keep issuing indy until all parties have updated their software, which may or may not be aligned with the issuer's technological choices. |
|
Let's discuss. We can call these out, as you say, but what is the "recommended" way? I think the recommended way to get the holders/verifiers software updated/ready (as best you can in a decentralized world), and then do the transition. If the criteria for keeping to issue the Indy-rooted credentials, how do you know what holder software has been updated? AFAIK the "discover features" protocol -- as useful as it is -- is not broadly implemented, and doesn't cover (for example) Indy to did:webvh transitions. |
…assumption and ongoing Indy credential management Signed-off-by: Patrick St-Louis <patrick.st-louis@opsecid.ca>
…py into docs/indy-to-webvh-migration
|
Addressed review feedback: reframed the guide around the full issuance process and a planned cutover (not dual-issuance), added the assumption that issuers/holders/verifiers already support did:webvh, and called out sharing new identifiers with verifiers before cutover and the need to keep managing already-issued Indy credentials (e.g. revocation). Also applied the copy edits (Phase 3 title, "register" not "re-register") and noted the pattern can apply to other VDR transitions. |
|
|
|
||
| ## Key Differences at a Glance | ||
|
|
||
| | Aspect | Indy | did:webvh | |
There was a problem hiding this comment.
A relative minor issue, but let me know what you think -- maybe a note early in the document? What you have in this table the "did:webvh Server AnonCreds Method" where the implementation is opinionated -- there is two extra elements in the DID (ns and id), plus a defined path to the resource. did:webvh itself can support any scheme -- "plain" did:webvh DIDs (no extra elements), any DID URL path. So we at least need to call that out vs. implying that this is what did:webvh requires.
It's too late for this, but I've wondered silently if the path should contain metadata such /resources/anoncreds-schema/{digest}. Did you consider that? Or the same mechanism that Indy used -- with the object type enumerated in the identifier.
|
|
||
| | Aspect | Indy | did:webvh | | ||
| |---|---|---| | ||
| | **Identifier format** | `WgWx...:2:name:1.0` (legacy) or `did:indy:sovrin:WgWx...` | `did:webvh:{SCID}:domain:ns:id/resources/{digest}` | |
There was a problem hiding this comment.
Might want to expand the Indy examples to include a the elements of a identifier data type.
|
|
||
| ### Phase 2 -- Verifier readiness | ||
|
|
||
| Give verifiers time to update their systems to accept credentials rooted in |
There was a problem hiding this comment.
I would expand this a bit more, to indicate that requires two things. Updated libraries that support resolving via the did:webvh AnonCreds Method, and updating the presentation request to add the equivalent did:webvh identifiers as an OR to the current Indy identifiers so that a wallet receiving the request can respond with whichever they are holding.
|
|
||
| Give verifiers time to update their systems to accept credentials rooted in | ||
| either the existing Indy identifiers or the new did:webvh identifiers. Once | ||
| verifiers can resolve did:webvh and include the new credential definition IDs |
There was a problem hiding this comment.
May not be a credential definition -- a presentation request can restrict on DID (issuer), schema and/or credential definition.
Might be worth putting in an example here -- before just indy and after Indy or did:webvh
| lifetime. They do not need to be re-issued. The issuer must **continue to | ||
| manage** those Indy credentials (e.g. process revocation and other status | ||
| updates) for as long as they are in use. | ||
| 3. You can remove the Indy ledger connection only when all Indy credentials |
There was a problem hiding this comment.
Perhaps make this Phase 4? Issuer notifies all parties (especially verifiers) that the Indy credentials have all been revoked. Issuers and verifiers (at their leisure) can then remove both the code and the presentation request configuration that uses/references Indy rooted-credentials. Verifiers only do that after all of the credential types they accept have been converted.
swcurran
left a comment
swcurran
left a comment
There was a problem hiding this comment.
Some comments that I think would make it a bit better (although it is great already). The only change is a clarification somewhere (presumably in the intro) that references the did:webvh AnonCreds Method is meant when it talks about switching to "did:webvh".
| - Databases: deploying/Databases.md | ||
| - Persistent Queues and Caching: deploying/RedisPlugins.md | ||
| - The askar-anoncreds Wallet Type: deploying/AnonCredsWalletType.md | ||
| - Migrating Issuance from Indy to did:webvh: deploying/IndyToWebVHMigration.md |
There was a problem hiding this comment.
Change to "Migrating AnonCreds Issuance..."
3 participants
Adds a strategic guide for issuers transitioning from Indy-based AnonCreds credentials to did:webvh-rooted ones. Covers prerequisites, dual-issuance transition strategy, step-by-step setup, and impact on controllers and verifiers.
Closes #3885